packages/shared/typedoc.json (1)

3-9: Use a recursive glob for hooks and verify duplicate symbols aren’t introduced

• The single-level glob may miss nested hooks. Prefer a recursive glob.
• Multiple entry points overlapping with exports from index.ts can produce duplicate symbols/pages in TypeDoc. Consider consolidating exports through index.ts or ensure no overlap.

Suggested change:

-    "./src/react/hooks/*.{ts,tsx}",
+    "./src/react/hooks/**/*.{ts,tsx}",

Please confirm:

• Are any hooks nested in subfolders under src/react/hooks?
• Does src/index.ts re-export any of react/types, react/hooks/*, react/commerce, or react/contexts, which could cause duplicates in the generated docs? If so, either remove the direct file entry points and rely on index.ts or adjust the exports to avoid duplication.

packages/shared/src/react/contexts.tsx (1)

28-46: Consider using interface instead of type, and remove the @interface JSDoc tag.

This type represents a simple object shape that could potentially be extended. Per the coding guidelines, interface should be preferred for such cases. Additionally, the @interface JSDoc tag is non-standard for TypeDoc—it automatically recognizes both interface and type declarations without requiring special annotations.

Apply this diff:

-/**
- * @interface
- */
-export type UseCheckoutOptions = {
+/**
+ * Options for configuring a checkout session.
+ */
+export interface UseCheckoutOptions {
   /**
    * Specifies if the checkout is for an organization.
    *
    * @default 'user'
    */
   for?: ForPayerType;
   /**
    * The billing period for the plan.
    */
   planPeriod: BillingSubscriptionPlanPeriod;
   /**
    * The ID of the subscription plan to check out (e.g. `cplan_xxx`).
    */
   planId: string;
-};
+}

packages/shared/src/react/commerce.tsx (3)

141-163: Consider using interface and improve wording on line 154.

Similar to UseCheckoutOptions, this is a simple object shape that should use interface per coding guidelines. The @interface JSDoc tag is unnecessary. Additionally, line 154's phrasing "whether to fetch for" is grammatically awkward.

Apply this diff:

-/**
- * @interface
- */
-export type PaymentElementProviderProps = {
+/**
+ * Props for the PaymentElementProvider component.
+ */
+export interface PaymentElementProviderProps {
   /**
    * An optional checkout resource object. When provided, the payment element is scoped to the specific checkout session.
    */
   checkout?: BillingCheckoutResource;
   /**
    * An optional object to customize the appearance of the Stripe Payment Element. This allows you to match the form's styling to your application's theme.
    */
   stripeAppearance?: internalStripeAppearance;
   /**
-   * Specifies whether to fetch for the current user or organization.
+   * Specifies whether the payment element is for the current user or organization.
    *
    * @default 'user'
    */
   for?: ForPayerType;
   /**
    * An optional description to display to the user within the payment element UI.
    */
   paymentDescription?: string;
-};
+}

---

243-251: Consider using interface instead of type, and remove the @interface JSDoc tag.

Consistent with the previous suggestions, this simple object shape should use interface per coding guidelines, and the @interface JSDoc tag is unnecessary.

Apply this diff:

-/**
- * @interface
- */
-export type PaymentElementProps = {
+/**
+ * Props for the PaymentElement component.
+ */
+export interface PaymentElementProps {
   /**
    * Optional fallback content, such as a loading skeleton, to display while the payment form is being initialized.
    */
   fallback?: ReactNode;
-};
+}

---

320-362: Remove the @interface JSDoc tag.

Unlike the previous types, this discriminated union is appropriately declared as a type (not interface) per coding guidelines, since it combines unions with object shapes. However, the @interface JSDoc tag is still unnecessary—TypeDoc will correctly document this type without it.

Apply this diff:

 /**
- * @interface
+ * Return type for the usePaymentElement hook.
  */
 export type UsePaymentElementReturn = {

packages/shared/src/react/hooks/usePlans.tsx (1)

27-30: Fix JSDoc tag and ensure public export for Typedoc visibility

• @interface on a type alias is incorrect and can confuse Typedoc. Add a short description and mark as @public.
• If usePlans is @internal, ensure the return type you expose is what you intend to document publicly.
• Export this type from the hooks barrel so Typedoc picks it up.

Apply:

-/**
- * @interface
- */
-export type UsePlansReturn = ReturnType<typeof usePlans>;
+/**
+ * Return type of the usePlans hook.
+ *
+ * @public
+ * @see usePlans
+ */
+export type UsePlansReturn = ReturnType<typeof usePlans>;

If createBillingPaginatedHook exposes a public generic result type (e.g., BillingPaginatedResult), prefer an explicit alias for clearer docs:

export type UsePlansReturn = BillingPaginatedResult<BillingPlanResource, GetPlansParams>;

Also update the barrel (packages/shared/src/react/hooks/index.ts):

export type { UsePlansReturn } from './usePlans';

Please confirm that UsePlansReturn appears in the generated Typedoc and renders the full shape (not just ReturnType<...>). If it doesn’t, consider the explicit alias approach above.

packages/types/src/clerk.ts (1)

82-84: Add a brief description before @inline
@inline is supported natively since TypeDoc v0.27.0 and will inline this union in the generated docs. Consider adding a one-line summary for clarity:

 /**
- * @inline
+ * Result of checkout operations for `start`/`confirm`.
+ * @inline
  */

packages/shared/src/react/types.ts (4)

116-121: Remove stray blank line in JSDoc to avoid extra paragraph in TypeDoc.
Small cleanup for consistent rendering.

  * @default undefined
  *
  * @hidden
- *
  * @experimental
  */

---

7-9: Avoid any in public types; prefer unknown as default.
Aligns with project guidelines and safer typing.

As per coding guidelines

-export type CacheSetter<CData = any> = (
+export type CacheSetter<CData = unknown> = (
   data?: CData | ((currentData?: CData) => Promise<undefined | CData> | undefined | CData),
 ) => Promise<CData | undefined>;

---

52-56: Fix off‑by‑one in JSDoc example for previous page (1‑based paging).
initialPage defaults to 1; previous page lower bound should be 1, not 0.

- * A function that triggers the previous page to be loaded. This is the same as `fetchPage(page => Math.max(0, page - 1))`.
+ * A function that triggers the previous page to be loaded. This is the same as `fetchPage(page => Math.max(1, page - 1))`.

---

82-85: Update stale comment to match type name.
Clarify doc to reflect PaginatedResources.

-// Utility type to convert PaginatedDataAPI to properties as undefined, except booleans set to false
+// Utility type to convert PaginatedResources to properties as undefined, except booleans set to false

packages/shared/src/react/hooks/useSubscription.tsx (2)

123-124: Make revalidate truly return Promise<void> and stabilize deps

mutate() resolves to Promise<Data | undefined>. Either reflect that in the type or wrap to return Promise<void>. Also prefer [swr] over [swr.mutate].

Apply this diff:

-  const revalidate = useCallback(() => swr.mutate(), [swr.mutate]);
+  const revalidate = useCallback(async () => {
+    await swr.mutate();
+  }, [swr]);

---

15-18: Remove non-standard @interface tags from JSDoc

@interface isn’t a TSDoc/TypeDoc tag and adds noise. Remove or replace with @public if needed.

Apply this diff:

-/**
- * @interface
- */
+/** */
@@
-/**
- * @interface
- */
+/** */
@@
-/**
- * @interface
- */
+/** */

Also applies to: 33-35, 43-45

.typedoc/extract-returns-and-params.mjs (4)

69-86: Handle “## Properties” fallback and normalize heading to “## Parameters”.

Some hooks render “Properties” instead of “Parameters”. Extract either, and when extracting “Properties”, rename the heading to “Parameters” for consistency.

Apply this diff:

-  // Find the "## Parameters" section
-  const paramsStart = content.indexOf('## Parameters');
+  // Find the "## Parameters" or "## Properties" section
+  const headingOptions = ['## Parameters', '## Properties'];
+  let headingUsed = '';
+  let paramsStart = -1;
+  for (const h of headingOptions) {
+    const idx = content.indexOf(h);
+    if (idx !== -1) {
+      headingUsed = h;
+      paramsStart = idx;
+      break;
+    }
+  }
 
   if (paramsStart === -1) {
     return false; // No Parameters section found
   }
 
-  // Find the next heading after "## Parameters" (or end of file)
-  const afterParams = content.slice(paramsStart + 13); // Skip past "## Parameters"
-  const nextHeadingMatch = afterParams.match(/\n## /);
+  // Find the next "## " heading after the found section (or end of file)
+  const headingLen = headingUsed.length;
+  const afterParams = content.slice(paramsStart + headingLen);
+  const nextHeadingMatch = afterParams.match(/(?:\r?\n)##\s/);
   const paramsEnd =
-    nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
-      ? paramsStart + 13 + nextHeadingMatch.index
+    nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
+      ? paramsStart + headingLen + nextHeadingMatch.index
       : content.length;
 
-  // Extract the Parameters section and trim trailing whitespace
-  const paramsContent = content.slice(paramsStart, paramsEnd).trimEnd();
+  // Extract the section and normalize heading to "## Parameters"
+  let paramsContent = content.slice(paramsStart, paramsEnd).trimEnd();
+  if (headingUsed === '## Properties') {
+    paramsContent = paramsContent.replace(/^## Properties\b/m, '## Parameters');
+  }

---

25-30: CRLF-safe next-heading detection for “Returns”.

Make heading detection robust across line endings and spacing.

Apply this diff:

-  // Find the next heading after "## Returns" (or end of file)
-  const afterReturns = content.slice(returnsStart + 10); // Skip past "## Returns"
-  const nextHeadingMatch = afterReturns.match(/\n## /);
+  // Find the next "## " heading after "## Returns" (or end of file)
+  const afterReturns = content.slice(returnsStart + 10); // Skip past "## Returns"
+  const nextHeadingMatch = afterReturns.match(/(?:\r?\n)##\s/);

---

128-134: Avoid hard-coding packages; discover under temp-docs.

To support more SDKs (e.g., nextjs, expo) without code changes, derive packages from temp-docs.

Example:

-function main() {
-  const packages = ['clerk-react'];
-  const dirs = packages.map(folder => path.join(__dirname, 'temp-docs', folder));
+function main() {
+  const docsRoot = path.join(__dirname, 'temp-docs');
+  const packages = fs.existsSync(docsRoot)
+    ? fs.readdirSync(docsRoot, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name)
+    : [];
+  const dirs = packages.map(folder => path.join(docsRoot, folder));

---

9-15: DRY the section-extraction logic.

extractReturnsSection and extractParametersSection share most logic (find heading, find next “## ”, slice, write). Consider a single helper: extractSection(filePath, { headingNames, outSuffix, deleteOldSuffixes?, normalize? }).

Also applies to: 47-55

packages/shared/src/react/hooks/createBillingPaginatedHook.tsx (1)

27-29: Use @typedef instead of @interface for type aliases.

The @interface JSDoc tag is intended for interface declarations. Since HookParams is defined using the type keyword (a type alias), consider using @typedef instead, or omit the tag entirely and let Typedoc infer the correct kind.

Apply this diff:

 /**
- * @interface
+ * @typedef HookParams
  */
 export type HookParams = PaginatedHookConfig<PagesOrInfiniteOptions> & {

Or simply remove the tag:

-/**
- * @interface
- */
 export type HookParams = PaginatedHookConfig<PagesOrInfiniteOptions> & {

.typedoc/custom-plugin.mjs (1)

46-49: Anchor-only replacements can produce double anchors

Mapping to "#use-..." while preserving the original anchor yields "#use-...#something". If anchors are ever present on source links, drop the captured anchor when newPath starts with "#".

Suggested change (outside this hunk) in getRelativeLinkReplacements:

-      replace: (/** @type {string} */ _match, anchor = '') => `(${newPath}${anchor})`,
+      replace: (/** @type {string} */ _match, anchor = '') =>
+        `(${newPath}${newPath.startsWith('#') ? '' : anchor})`,

Also confirm the target headings exist for:

• #use-checkout-options
• #use-reverification-options
• #needs-reverification-parameters

packages/shared/src/react/hooks/useReverification.ts (2)

14-16: Remove or complete empty JSDoc; mark internal helpers explicitly

This empty block will surface as noise in Typedoc. Either document resolveResult properly and mark it @internal, or remove the block.

-/**
- *
- */
+/**
+ * @internal
+ * Normalize a fetcher result by unwrapping `Response` bodies and converting Clerk reverification API errors
+ * into a reverification hint.
+ *
+ * @template T
+ * @param result A promise or value returned by a fetcher.
+ * @returns The resolved value, or a reverification hint wrapper.
+ */

---

95-101: Document internal helpers or remove placeholder blocks

createReverificationHandler/assertReverification are internal. Empty JSDoc blocks reduce clarity and pollute docs.

-/**
- */
+/**
+ * @internal
+ * Creates a handler that wraps a fetcher with a reverification flow.
+ */
 function createReverificationHandler(params: CreateReverificationHandlerParams) {
-  /**
-   *
-   */
+  /**
+   * @internal
+   * Wraps a fetcher to intercept reverification hints, show UI or call the custom handler,
+   * and retry the original fetch on success.
+   */
   function assertReverification<Fetcher extends (...args: any[]) => Promise<any> | undefined>(

packages/types/src/billing.ts (2)

705-731: Strengthen ConfirmCheckoutParams to enforce mutual exclusivity and required fields

Current union members use optional fields, allowing {} and not enforcing the “only one of …” rule. Make fields required per branch and model the XOR intent.

-export type ConfirmCheckoutParams =
-  | {
-      /**
-       * The ID of a saved payment method to use for this checkout.
-       */
-      paymentSourceId?: string;
-    }
-  | {
-      /**
-       * A token representing payment details, usually from a payment form. **Requires** `gateway` to be provided.
-       */
-      paymentToken?: string;
-      /**
-       * The payment gateway to use. **Required** if `paymentToken` or `useTestCard` is provided.
-       */
-      gateway?: PaymentGateway;
-    }
-  | {
-      /**
-       * The payment gateway to use. **Required** if `paymentToken` or `useTestCard` is provided.
-       */
-      gateway?: PaymentGateway;
-      /**
-       * If true, uses a test card for the checkout. **Requires** `gateway` to be provided.
-       */
-      useTestCard?: boolean;
-    };
+export type ConfirmCheckoutParams =
+  | {
+      /** The ID of a saved payment method to use for this checkout. */
+      paymentSourceId: string;
+    }
+  | {
+      /** A token representing payment details, usually from a payment form. */
+      paymentToken: string;
+      /** The payment gateway to use. */
+      gateway: PaymentGateway;
+    }
+  | {
+      /** The payment gateway to use. */
+      gateway: PaymentGateway;
+      /** If true, uses a test card for the checkout. */
+      useTestCard: boolean;
+    };

As per coding guidelines

---

309-309: Prefer optional property over string | undefined

For consistency with the rest of the file, use walletType?: string instead of string | undefined.

-  walletType: string | undefined;
+  walletType?: string;

As per coding guidelines

packages/shared/src/react/hooks/useCheckout.ts (1)

114-121: Consider adding @returns in function JSDoc for public API completeness

To meet “All public APIs must be documented with JSDoc,” add a returns description for useCheckout.

 /**
  * @function
  *
  * @param [options] - An object containing the configuration for the checkout flow.
  *
  * **Required** if the hook is used without a `<CheckoutProvider />` wrapping the component tree.
+ *
+ * @returns An object containing the `checkout` API with typed status, data, and actions.
  */

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

.typedoc/custom-plugin.mjs (1)

33-33: Fix the typo in the filename.

Line 33 has a comma instead of a period before 'mdx'. This typo prevents the heading removal logic from matching the file correctly.

Apply this diff:

-  'use-reverification-params,mdx',
+  'use-reverification-params.mdx',

packages/shared/src/react/hooks/useCheckout.ts (1)

94-97: Finalize return type mismatch and JSDoc option name

API returns Promise<void> and accepts { navigate?: SetActiveNavigate }. Update type and docs to match.

     /**
-     * A function that finalizes the checkout process. Can optionally accept a `redirectUrl` to navigate the user to upon completion.
+     * Finalizes the checkout process. Optionally accepts a `navigate` callback to control post-completion navigation.
      */
-    finalize: (params?: { navigate?: SetActiveNavigate }) => void;
+    finalize: (params?: { navigate?: SetActiveNavigate }) => Promise<void>;

Based on relevant snippets (packages/types/src/clerk.ts).

packages/shared/src/react/hooks/useReverification.ts (2)

40-53: Make parameters readonly and prefer optional property syntax

Improves API clarity and matches typical TS style for immutable callback containers.

-export type NeedsReverificationParameters = {
-  /**
-   * Marks the reverification process as cancelled and rejects the original request.
-   */
-  cancel: () => void;
-  /**
-   * Marks the reverification process as complete and retries the original request.
-   */
-  complete: () => void;
-  /**
-   * The verification level required for the reverification process.
-   */
-  level: SessionVerificationLevel | undefined;
-};
+export type NeedsReverificationParameters = {
+  /**
+   * Cancels the reverification process and rejects the original request.
+   */
+  readonly cancel: () => void;
+  /**
+   * Marks reverification complete and retries the original request.
+   */
+  readonly complete: () => void;
+  /**
+   * The verification level required for the reverification process.
+   */
+  readonly level?: SessionVerificationLevel;
+};

---

14-16: Replace placeholder JSDoc with concise summaries (improves Typedoc quality)

Empty blocks degrade docs quality.

 /**
- *
+ * Normalize fetcher results: unwrap Response to JSON and map Clerk reverification error code to a sentinel.
  */

-/**
- */
+/**
+ * Internal: creates a reverification-aware wrapper that intercepts hints and retries after completion.
+ */
 function createReverificationHandler(params: CreateReverificationHandlerParams) {
-  /**
-   *
-   */
+  /**
+   * Wrap the provided fetcher to handle reverification hints.
+   */
   function assertReverification<Fetcher extends (...args: any[]) => Promise<any> | undefined>(

Note: If you apply the earlier generic fix, also remove | undefined here.

Also applies to: 95-101

packages/shared/src/react/hooks/useCheckout.ts (1)

112-113: Export UseCheckoutParams so Typedoc can surface it

Unexported types won’t appear in generated docs, undermining the PR goal.

-type UseCheckoutParams = Parameters<typeof __experimental_CheckoutProvider>[0];
+export type UseCheckoutParams = Parameters<typeof __experimental_CheckoutProvider>[0];

If this is re-exported elsewhere already, feel free to skip; otherwise, exporting here helps Typedoc discover it.

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

packages/shared/src/react/hooks/useReverification.ts (3)

72-75: Disallow undefined in Fetcher generic for UseReverificationResult (duplicate of prior feedback).

Fetcher must be a function; allowing undefined is incorrect and weakens typing/inference.

As per coding guidelines (avoid any/invalid types).

-type UseReverificationResult<Fetcher extends (...args: any[]) => Promise<any> | undefined> = (
+type UseReverificationResult<Fetcher extends (...args: any[]) => Promise<any>> = (
   ...args: Parameters<Fetcher>
 ) => Promise<ExcludeClerkError<Awaited<ReturnType<Fetcher>>>>;

---

58-67: Fix JSDoc for onNeedsReverification to document the single properties object (duplicate of prior feedback).

Current tags list non-existent params (cancel, complete, level). Document the single properties param with nested fields so TypeDoc matches the actual signature.

As per coding guidelines (public APIs must be correctly documented). Apply:

   /**
-   * A handler that is called when reverification is needed, this will opt-out of using the default UI when provided.
-   *
-   * @param cancel - A function that will cancel the reverification process.
-   * @param complete - A function that will retry the original request after reverification.
-   * @param level - The level returned with the reverification hint.
+   * A handler called when reverification is needed. Providing this opts out of the default UI.
+   *
+   * @param properties - Callbacks and info to control the reverification flow.
+   * @param properties.cancel - Cancels reverification and rejects the original request.
+   * @param properties.complete - Marks reverification complete and retries the original request.
+   * @param properties.level - The verification level required.
    */
   onNeedsReverification?: (properties: NeedsReverificationParameters) => void;

---

79-88: Tighten UseReverification signature to disallow undefined fetchers (duplicate of prior feedback).

Strengthen the constraint to require a function; improves inference and TypeDoc accuracy.

-type UseReverification = <Fetcher extends (...args: any[]) => Promise<any> | undefined>(
+type UseReverification = <Fetcher extends (...args: any[]) => Promise<any>>(
   /**
    * A function that returns a promise.
    */
   fetcher: Fetcher,
   /**
    * The optional options object.
    */
   options?: UseReverificationOptions,
 ) => UseReverificationResult<Fetcher>;

.typedoc/extract-returns-and-params.mjs (1)

61-110: Write -params next to the source MDX and delete -props from the same folder (duplicate of prior feedback).

Currently uses dirName (package root), causing misplaced files and wrong deletions.

Apply these diffs:

- * @param {string} dirName - The directory containing the files
  * @returns {boolean} True if a file was created
  */
-function extractParametersSection(filePath, dirName) {
+function extractParametersSection(filePath) {
   const content = fs.readFileSync(filePath, 'utf-8');
   const fileName = path.basename(filePath, '.mdx');

   const propsFileName = `${fileName}-props.mdx`;

   // Delete any existing -props file (TypeDoc-generated)
-  const propsFilePath = path.join(dirName, propsFileName);
+  const dirForFile = path.dirname(filePath);
+  const propsFilePath = path.join(dirForFile, propsFileName);

   // Write to new file
-  const newFilePath = path.join(dirName, targetFileName);
+  const newFilePath = path.join(dirForFile, targetFileName);
   fs.writeFileSync(newFilePath, paramsContent, 'utf-8');

-      // Extract Parameters sections
-      if (extractParametersSection(filePath, dir)) {
+      // Extract Parameters sections
+      if (extractParametersSection(filePath)) {
         paramsCount++;
       }

Also applies to: 170-174

packages/shared/src/react/hooks/useReverification.ts (3)

101-104: Align internal generic with stricter Fetcher constraint.

Ensure assertReverification also disallows undefined.

-  function assertReverification<Fetcher extends (...args: any[]) => Promise<any> | undefined>(
+  function assertReverification<Fetcher extends (...args: any[]) => Promise<any>>(
     fetcher: Fetcher,
   ): (...args: Parameters<Fetcher>) => Promise<ExcludeClerkError<Awaited<ReturnType<Fetcher>>>> {

---

40-53: Prefer readonly fields and optional level for public type clarity.

Improves ergonomics and communicates immutability without runtime change.

-export type NeedsReverificationParameters = {
+export type NeedsReverificationParameters = {
   /**
    * Marks the reverification process as cancelled and rejects the original request.
    */
-  cancel: () => void;
+  readonly cancel: () => void;
   /**
    * Marks the reverification process as complete and retries the original request.
    */
-  complete: () => void;
+  readonly complete: () => void;
   /**
    * The verification level required for the reverification process.
    */
-  level: SessionVerificationLevel | undefined;
+  readonly level?: SessionVerificationLevel;
 };

---

14-16: Remove empty JSDoc block or add a brief description.

Empty blocks add noise and can confuse TypeDoc.

-/**
- *
- */
+/** Normalize fetcher results and map Clerk reverification errors to a hint shape. */

packages/shared/src/react/commerce.tsx (1)

4-4: Use type-only import for ReactNode to avoid pulling it into runtime.

Improves tree-shaking and aligns with “type-only imports where possible.”

As per coding guidelines.

-import React, { type PropsWithChildren, ReactNode, useCallback, useEffect, useMemo, useState } from 'react';
+import React, { useCallback, useEffect, useMemo, useState } from 'react';
+import type { PropsWithChildren, ReactNode } from 'react';

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.